home *** CD-ROM | disk | FTP | other *** search
/ Gold Medal Software 3 / Gold Medal Software - Volume 3 (Gold Medal) (1994).iso / archive / cx201e.arj / CX.DOC < prev    next >
Text File  |  1994-03-01  |  37KB  |  868 lines
  1.  
  2.                       ███      ███   ███  █ 
  3.                       █          █   █ █ ██ 
  4.                       █   █ █  ███   █ █  █ 
  5.                       █    █   █     █ █  █ 
  6.                       ███ █ █  ███ █ ███ ███
  7.  
  8.            Copyright (c) 1987-1994 Four Lakes Computing
  9.  
  10.  
  11. Hello!
  12. --------------------------------------------------------------------------
  13. This manual and the included test programs should give you a good idea of
  14. how to use Cx.  If you have ANY questions or want to talk to a knowledgeable
  15. person about Cx, or data compression in general, PLEASE call or send a
  16. note to:
  17.  
  18.    *  Compuserve     70662,2501
  19.    *  US Telephone   (608) 256-3382
  20.    *  US Address     Four Lakes Computing
  21.                      1135 Williamson #4
  22.                      Madison, WI 53703
  23.  
  24. All questions welcome.  No sales pressure.  Promise!
  25.  
  26. Many applications (like backup programs) which must have complete data
  27. integrity are currently using Cx.  Cx is used with MS-DOS, Windows, OS/2,
  28. Macintosh, and even some UNIX applications.  Applications which use Cx are
  29. written in C, C++, Pascal, Assembly, BASIC, Visual BASIC and others.  Cx
  30. is used by very small companies as well as very large corporations.  In
  31. short, you don't have to worry about support, porting, bugs, or royalties
  32. when you use Cx.
  33.  
  34. The purchasers of Cx have found Cx to be the highest performance data
  35. compression library that is commercially available (customer comments are
  36. included below).  In addition, Cx may be purchased with very portable
  37. source code to further protect your investment. 
  38.  
  39. Cx 2.01 is priced at $145 ($295 with ANSI C and 80x86 assembly source).
  40. Cx 2.01 is royalty free.  A one time purchase fee grants you the right
  41. to use Cx 2.01 in any or all of your applications.
  42.  
  43.  
  44. Using this manual
  45. --------------------------------------------------------------------------
  46. This manual has the following sections:
  47.  
  48.       *  Comments from Cx Users                                *
  49. ->    *  Evaluation Package Differences  (IMPORTANT!)          *
  50.       *  Included Files                                        *
  51.       *  What's New                                            *
  52.       *  Upgrading from Cx 1.*                                 *
  53.       *  Benchmarks                                            *
  54.       *  Using Cx                                              *
  55.       *  The Cx Programming Interface                          *
  56.       *  Programming, Compiler, Environment Notes              *
  57.       *  Where is the Object Code? / The Object Code Manager   *
  58.       *  The CXF Source Code                                   *
  59.       *  Cx 2.01 Ordering Information                          *
  60.  
  61.  
  62. Comments from Cx Users
  63. --------------------------------------------------------------------------
  64. The following quotes pertain to Cx versions 1.* and 2.01, and ALL quotes
  65. are used with the permission of the authors (Cx 2.01 was released in
  66. February 1994).
  67.  
  68.    *  My initial tests show great advantage over my current technique!
  69.          - 29-Aug-92  Norm Patriquin, CIS: 70254,643
  70.  
  71.    *  For your information, I currently use another well known compression
  72.       library for my backup product and you appear to be 30% faster than
  73.       their routines.  Their compression library has been detuned and
  74.       does not operate as fast as their stand alone programs.
  75.          - 01-Sep-92  Norm Patriquin, CIS: 70254,643
  76.  
  77.    *  Well, we have made all the code changes in MegaBack [tm], and your
  78.       compression routines work great!  Our experience with method 1 is
  79.       a 23% [speed] improvement over the compression done by the other
  80.       popular compression library and it even reduced the size of the
  81.       compressed data!
  82.          - 11-Sep-92  Norm Patriquin, CIS: 70254,643
  83.  
  84.    *  Your product is MUCH BETTER than your CX.DOC advertises!
  85.          - 19-Apr-93  E. Nicholas Cupery, author of the Farba Utilities (tm)
  86.  
  87.    *  Yours is a fine product, and it's great to deal with someone
  88.       so *responsive*.
  89.          - 19-Apr-93  E. Nicholas Cupery, author of the Farba Utilities (tm)
  90.  
  91.    *  ... because ___ Inc and I are so closely linked I don't publicly
  92.       endorse products, however, I would like to personally congratulate
  93.       you on a fine product.  Again, thanks for a fine product.
  94.          - 13-May-93  Unnamed
  95.  
  96.    *  BOTTOM LINE:  It looks to me like your new CX v2.01 is a significant
  97.       improvement.
  98.          -  2-Feb-94  E. Nicholas Cupery, author of the Farba Utilities (tm)
  99.  
  100.    *  I currently use the Cx compression routines in all my products and
  101.       recommend them highly.  I have tried several other compression
  102.       libraries and yours are clearly the fastest and best!
  103.          - 17-Feb-94  Norm Patriquin, CIS: 70254,643
  104.  
  105.  
  106. Evaluation Package Differences
  107. --------------------------------------------------------------------------
  108. The differences between the evaluation package and the purchaseable
  109. package are entirely contained in the object code.  In all other respects
  110. the evaluation and purchaseable packages are identical.
  111.  
  112. !! The included program TEST.EXE may be used for determining the EXACT
  113. !! speed and compression levels of the purchaseable object and source code.
  114.  
  115. The evaluation package contains different object code from that which
  116. may be purchased.  The interface, however, is IDENTICAL.  The differences
  117. in the evaluation package object code are listed below:
  118.  
  119.    *  The object code included in the evaluation package runs MUCH
  120.       slower than the object code that may be purchased.
  121.  
  122.    *  All methods in the evaluation object code compress to the same
  123.       level (namely CX_METHODC).
  124.  
  125.    *  The evaluation object code will not run indefinitely.
  126.  
  127.    *  The evaluation object code has a slightly different size than
  128.       the object code that may be purchased.
  129.  
  130.    *  The evaluation object code may only be used for evaluating the
  131.       interface to Cx.  NO other usage or distribution rights are
  132.       granted.
  133.  
  134.  
  135. Included Files
  136. --------------------------------------------------------------------------
  137.    TEST.EXE       -  Cx 2.01 Test/Benchmark program
  138.  
  139.    CX.DOC         -  this document
  140.    LICENSE.DOC    -  license for Cx 2.01 (read before purchasing)
  141.    ORDER.DOC      -  ordering information
  142.    VENDOR.DOC     -  information for vendors and distributors of Cx
  143.    COMMENTS.DOC   -  comments from Cx users
  144.    FILE_ID.DIZ    -  BBS compatible description of Cx
  145.    SOURCE.DOC     -  Included with source code purchase only.
  146.  
  147.    CX.H           -  C/C++ interface to Cx
  148.    CX.PAS         -  Pascal interface to Cx
  149.    CX.BAS         -  BASIC interface to Cx
  150.    CXEQU.ASM      -  80x86 assembly interface to Cx
  151.    VBCX.BAS       -  Visual BASIC interface to CX
  152.  
  153.    CXSUB.DOC      -  documentation for CXSUB routines
  154.    CXSUB.C        -  CXSUB C/C++ routines
  155.    CXSUB.H        -  CXSUB C/C++ interface
  156.    CXSUB.PAS      -  CXSUB Pascal routines and interface
  157.    VBCXSUB.BAS    -  CXSUB Visual BASIC routines and interface
  158.  
  159.    CXF.C          -  C/C++ example program
  160.    CXF.BAS        -  BASIC example program
  161.    CXF.PAS        -  Pascal example program
  162.  
  163.    VBCXF.MAK      -  Visual BASIC example project file
  164.    VBCXF.FRM      -  Visual BASIC example form
  165.  
  166.    BINIO.DOC      -  documentation for BINIO.DLL
  167.    BINIO.DLL      -  Windows 3.*+ DLL for binary file I/O
  168.    BINIO.LIB      -  Windows 3.*+ import library for BINIO.DLL
  169.    VBBINIO.BAS    -  Visual BASIC interface to BINIO.DLL
  170.    
  171.    MCXF.BAT       -  MS-DOS batch file to compile test programs
  172.    MCXF.CMD       -  OS/2 batch file to compile test programs
  173.  
  174.    OCM.EXE        -  Object Code Manager
  175.    OCM.DAT        -  Cx 2.01 Object Code
  176.  
  177.    WINIO.OBJ      -  Object file that allows C based Windows programs
  178.                      to emulate console programs.  This data is provided
  179.                      courtesy of Microsoft Systems Journal, Andrew
  180.                      Schulman and Dave Maxey, and is available on
  181.                      Compuserve in the Microsoft Languages Forum (GO MSL)
  182.                      as files S13103.ZIP and S13155.ZIP.
  183.  
  184.    *.DOC          -  Documentation files
  185.    VB*.*          -  Visual BASIC files
  186.  
  187.  
  188. What's New
  189. --------------------------------------------------------------------------
  190. Cx 2.01 features:
  191.  
  192.    *  100% compatibility with Cx 1.* compressed data and CRCs.
  193.    *  A new super fast compression method (60% + faster than Cx 1.*).
  194.    *  A new super fast decompression method (60%+ faster than Cx 1.*).
  195.    *  Generally faster and smaller compression than Cx 1.* methods.
  196.    *  Faster CRC computation.
  197.    *  Better object code organization for a potential RAM reduction.
  198.  
  199.  
  200. Upgrading from Cx 1.*
  201. --------------------------------------------------------------------------
  202.    The programming interface to Cx has remained the same, although the
  203.    values of two constants have changed (CX_C_MINTEMP and CX_D_MINTEMP).
  204.  
  205.    Two new compression methods have been added, CX_METHODC and CX_METHODD.
  206.    These allow for faster compression or decompression.
  207.  
  208.    Using the Object Code Manager, it is now possible to tailor the Cx
  209.    object code for reduced memory requirements.
  210.  
  211.    Using the Object Code Manager, you can include Cx 1.* decompression
  212.    compatibility.
  213.    
  214.    That's it!
  215.  
  216.  
  217. Benchmarks
  218. --------------------------------------------------------------------------
  219. The included program TEST.EXE may be used for comparing Cx with other
  220. compression products.  TEST.EXE uses the CXSUB routines (source code
  221. is included here), and is compiled using Microsoft C 8.00.
  222.  
  223. These benchmarks where produced on a 386 40 MHZ PC, using TEST.EXE.
  224. The headings indicate:
  225.  
  226.    C.TST    -  1MB of C source files
  227.    AP.TST   -  1MB of Associated Press wire stories (in English)
  228.    EXE.TST  -  1MB of executable programs
  229.    SIZE     -  relative size
  230.    CTIME    -  relative compression time
  231.    DTIME    -  relative decompression time
  232.  
  233. All measurements are relative, with 1.00* indicating the best performance.
  234.  
  235.              C.TST                 AP.TST                EXE.TST
  236.              SIZE   CTIME  DTIME   SIZE   CTIME  DTIME   SIZE   CTIME  DTIME
  237.              ---------------------------------------------------------------
  238. PKZIP 2.04g  1.00*| 2.07 | 1.27    1.00*| 2.07 | 1.00*   1.00*| 1.63 | 1.18
  239. PKZIP 1.1    1.14 | 3.18 | 1.27    1.13 | 2.57 | 1.00*   1.08 | 2.33 | 1.00*
  240. lharc 1.13c  1.25 | 9.16 | 5.73    1.22 | 3.43 | 4.74    1.08 | 3.30 | 6.76
  241. lha 2.13     1.12 | 5.59 | 2.58    1.12 | 3.68 | 2.37    1.04 | 2.60 | 2.64
  242. arj 2.30     1.01 | 4.18 | 2.31    1.01 | 3.37 | 2.02    1.01 | 2.59 | 2.42
  243. pak 2.51     1.18 | 4.59 | 3.08    1.15 | 3.01 | 2.30    1.08 | 2.60 | 2.80
  244. arc 6.02     1.98 | 2.32 | 5.04    1.55 | 1.75 | 3.65    1.41 | 1.58 | 3.93
  245. Cx 2.01/c    1.40 | 1.00*| 1.15    1.42 | 1.00*| 1.19    1.11 | 1.00*| 1.02
  246. Cx 2.01/d    1.19 | 2.47 | 1.00*   1.22 | 2.10 | 1.05    1.05 | 2.14 | 1.00*
  247. Cx 2.01/1    1.19 | 2.30 | 1.54    1.20 | 1.85 | 1.53    1.05 | 1.76 | 1.40
  248. Cx 2.01/2    1.13 | 3.06 | 4.73    1.13 | 2.34 | 3.84    1.04 | 2.29 | 3.71
  249. Cx 2.01/3    1.10 | 3.65 | 6.38    1.10 | 2.78 | 4.95    1.04 | 2.99 | 6.93
  250.  
  251. PKZIP (tm) is a trademark of PKWARE, Inc.
  252.  
  253. Note that some of the providers of the listed programs also provide
  254. compression libraries, and these libraries may have very different
  255. performance characteristics.  For direct comparisons between libraries,
  256. it is suggested that you obtain free evaluation packages from these
  257. providers.
  258.  
  259. Some of the highlights of this data:
  260.  
  261.    *  Cx 2.01/c is at least 60% faster when compressing than any other
  262.       algorithm.  Typically 2 to 3 times faster.
  263.  
  264.    *  Cx 2.01/d is always within 5% of the fastest decompressor, and
  265.       provides very good compression.
  266.  
  267.    *  Cx 2.01/1 performs much better than lharc 1.13c (perhaps the most
  268.       popular compressor ever made) in all measurements, usually be a
  269.       wide margin.
  270.  
  271.    *  Cx 2.01/2 and Cx 2.01/3 compress within 13% of the best compressors.
  272.  
  273.  
  274. Using Cx
  275. --------------------------------------------------------------------------
  276. Cx is a data compression programming library.  As such, it can not do
  277. anything on it's own.  An application which uses Cx must be created.  Cx
  278. was designed so it would not imply anything about the application that
  279. is using it, or the language the application was written in.  Application
  280. writers have a lot of versatility in the ways they can use Cx.
  281.  
  282. Cx does not know anything about files, archive formats or serial
  283. communications.  Cx knows about memory buffers.  A memory buffer is
  284. simply an area of memory.  For Cx to compress or decompress data,
  285. the calling application needs to tell Cx about three memory buffers:
  286.  
  287.    * The source of input data.
  288.    * The destination of output data.
  289.    * An area of memory that Cx may use for temporary storage.
  290.  
  291. The application also needs to tell Cx how big these memory buffers are
  292. so that Cx will not access any memory outside of this area.  With the
  293. three buffers and the three associated sizes, a total of 6 parameters
  294. are needed to the Cx compression and decompression routines.
  295.  
  296. The only other parameter is to the Cx compression routine.  This parameter
  297. tells Cx what method of compression to use.  This gives your application
  298. the ability to balance compression size, compression speed and decompression
  299. speed.
  300.  
  301. As mentioned earlier, Cx does not know anything about files.  It is not
  302. much harder, however, to write a routine that compresses a file using Cx
  303. than to write a routine to simply copy a file.  Routines to compress
  304. one file to another are provided in the included source code files.
  305.  
  306. The hardest part about using Cx is correctly setting up the parameters
  307. to be passed.  The programming interface found below is fairly terse,
  308. but provides precise information about using Cx.
  309.  
  310.  
  311.  
  312. The Cx Programming Interface
  313. --------------------------------------------------------------------------
  314. This programming interface does not imply any language or environment.
  315. See the section 'Programming, Compiler, Environment Notes' for more
  316. information, or see the following Cx interface files:
  317.  
  318.       CX.H
  319.       CX.PAS
  320.       CX.BAS
  321.       VBCX.BAS
  322.       CXASM.EQU
  323.  
  324. When interfacing to a language which can not use one of these interface
  325. files, consult one of them for the exact values of constants.  It is
  326. suggested that you create a similar interface file for the language
  327. you are using.
  328.  
  329. It is very important to use the constants included in the interface
  330. files, as they may change in future versions of Cx.
  331.  
  332.  
  333.    Data Types
  334.    -------------------------------------------------------------------
  335.    CXINT             -  A 16 bit unsigned integer.
  336.    CXINTSIZE         -  The size of CXINT (2 bytes).
  337.    CXBUFF            -  A 32 bit pointer to a buffer.
  338.    CXCALL            -  32 bit (far) Pascal calling convention
  339.  
  340.  
  341.    Constants
  342.    -------------------------------------------------------------------
  343.    CX_ERR_INVALID    -  Error code returned by Cx routines.
  344.    CX_ERR_METHOD     -  ...
  345.    CX_ERR_BUFFSIZE   -  ...
  346.    CX_ERR_TEMPSIZE   -  ...
  347.  
  348.    CX_METHODC        -  Identifies compression method C.
  349.    CX_METHODD        -  Identifies compression method D.
  350.    CX_METHOD1        -  Identifies compression method 1.
  351.    CX_METHOD2        -  Identifies compression method 2.
  352.    CX_METHOD3        -  Identifies compression method 3.
  353.  
  354.    CX_MAX_BUFFER     -  The maximum buffer size that may be compressed.
  355.  
  356.    CX_SLOP           -  The amount the Cx routines may overrun
  357.                         compressed buffers.
  358.  
  359.    CX_C_MINTEMP      -  The minimum amount of temporary memory the
  360.                         Cx compression routine needs.
  361.  
  362.    CX_C_MAXTEMP      -  The maximum amount of temporary memory the
  363.                         Cx compression routine can use.
  364.  
  365.    CX_D_MINTEMP      -  The minimum amount of temporary memory the
  366.                         Cx decompression routine needs.  Note that
  367.                         there is no CX_D_MAXTEMP because the Cx
  368.                         decompression routine does not need and will
  369.                         not use more than CX_D_MINTEMP.
  370.  
  371.  
  372.    Function CX_COMPRESS(method, obuff, osize, ibuff, isize, tbuff, tsize)
  373.    ----------------------------------------------------------------------
  374.    PARAMETERS:
  375.       method   
  376.             Method of data compression to use (one of the CX_METHOD*
  377.             constants).
  378.  
  379.       obuff    
  380.             Output buffer where compressed data is to be placed.
  381.  
  382.       osize
  383.             Size of obuff.  osize must be within the range
  384.             [0..CX_MAX_BUFFER].  CX_COMPRESS must have read/write
  385.             access to bytes [0..osize+CX_SLOP-1] in obuff.
  386.  
  387.       ibuff    
  388.             Input buffer containing data to compress.  The contents
  389.             of ibuff are not modified by CX_COMPRESS.
  390.  
  391.       isize    
  392.             Bytes of data in ibuff to compress.  isize must be
  393.             within the range [0..CX_MAX_BUFFER]. 
  394.  
  395.       tbuff    
  396.             A buffer that will be used by Cx for temporary storage.
  397.  
  398.       tsize
  399.             Size of tbuff.  Cx needs at least CX_C_MINTEMP bytes of
  400.             temporary storage while compressing, but can make use
  401.             of up to CX_C_MAXTEMP bytes.  The more temporary
  402.             storage provided to Cx, the greater the potential for
  403.             compression.  tsize must be within the range
  404.             [CX_C_MINTEMP..CX_C_MAXTEMP].
  405.  
  406.    RETURN VALUE:
  407.  
  408.       CX_ERR_METHOD
  409.             The compression method requested is invalid or
  410.             unsupported in the called version of CX_COMPRESS.
  411.  
  412.       CX_ERR_BUFFSIZE
  413.             isize or osize is not within the range [0..CX_MAX_BUFFER].
  414.  
  415.       CX_ERR_TEMPSIZE
  416.             size is not within the range [CX_C_MINTEMP..CX_C_MAXTEMP].
  417.    
  418.       isize    (if the value in passed parameter isize is returned)
  419.             The data in ibuff was not compressable or would not fit
  420.             into obuff.  In this case, no assumptions about the
  421.             contents of obuff should be made.
  422.  
  423.       else     (if none of the above, the typical return)
  424.             The data in ibuff was successfully compressed to obuff.
  425.             The return value is the number of compressed bytes
  426.             placed in obuff.
  427.  
  428.  
  429.    Function CX_DECOMPRESS(obuff, osize, ibuff, isize, tbuff, tsize)
  430.    ----------------------------------------------------------------------
  431.    PARAMETERS:
  432.  
  433.       obuff 
  434.          Output buffer where decompressed data is to be placed.
  435.    
  436.       osize 
  437.             Size of obuff.  Usually, osize will be the number of
  438.             bytes that where compressed into ibuff, but osize may
  439.             be smaller, allowing for partial decompression of a
  440.             buffer.  CX_DECOMPRESS must have write access to bytes
  441.             [0..osize] in obuff.
  442.    
  443.       ibuff 
  444.             Input buffer containing data compressed with Cx.  The
  445.             contents of ibuff are not modified by CX_DECOMPRESS.
  446.    
  447.       isize 
  448.             Size of ibuff.  CX_DECOMPRESS recognizes the end of the
  449.             compressed data in ibuff by a special 'End of Data'
  450.             symbol, NOT by consulting isize.  isize is used to
  451.             prevent CX_DECOMPRESS from accessing memory it should not
  452.             when the data in ibuff is invalid or corrupt.  isize must be
  453.             within the range [0..CX_MAX_BUFFER].   CX_DECOMPRESS must have
  454.             read access to bytes [0..isize+CX_SLOP-1] in ibuff.
  455.    
  456.       tbuff 
  457.             A buffer that will be used by Cx for temporary storage.
  458.    
  459.       tsize 
  460.             Size of tbuff.  tsize must be at least CX_D_MINTEMP. 
  461.             CX_DECOMPRESS does not need (and will not use or access)
  462.             more than CX_D_MINTEMP bytes of temporary storage.
  463.    
  464.    RETURN VALUE:
  465.  
  466.       CX_ERR_METHOD
  467.             The data in ibuff is invalid, corrupt, or was
  468.             compressed with a method not supported in the called
  469.             version of CX_DECOMPRESS.
  470.  
  471.       CX_ERR_INVALID
  472.             The data in ibuff is invalid or corrupt, and can not be
  473.             completely decompressed.  In this case, CX_DECOMPRESS
  474.             may be called with different values of osize to find
  475.             the largest amount of data that can be decompressed
  476.             without an error.
  477.  
  478.       CX_ERR_BUFFSIZE
  479.             isize is not within the range [0..CX_MAX_BUFFER].
  480.    
  481.       CX_ERR_TEMPSIZE
  482.             tsize is smaller than CX_D_MINTEMP.
  483.  
  484.       else     (if none of the above, the typical return)
  485.             The data in ibuff was successfully decompressed into
  486.             obuff.  The return value is the number of decompressed
  487.             bytes placed into obuff.
  488.  
  489.  
  490.    Function CX_CRC(buff, bytes)
  491.    --------------------------------------------------------------
  492.    PARAMETERS:
  493.  
  494.       buff 
  495.             Buffer to compute 16 bit Cyclical Redundancy Check (CRC) on.
  496.  
  497.       bytes
  498.             The number of bytes in buff.
  499.  
  500.    RETURN VALUE:
  501.  
  502.       16 bit CRC
  503.       
  504.  
  505. Programming, Compiler, Environment Notes
  506. ---------------------------------------------------------------------
  507. The following is a collection of notes that provide more specific
  508. information on a variety of subjects:
  509.  
  510.    * Choosing a Compression Method                    *
  511.    * What is CX_SLOP?                                 *
  512.    * Memory Considerations / Low Memory Situations    *
  513.    * Re-entrancy                                      *
  514.    * Handling Uncompressable Data                     *
  515.    * Detecting Errors / Using a CRC                   *
  516.    * Interfacing to 80x86 Object Code                 *
  517.    * Using Unsigned Integers.                         *
  518.    * Building a Turbo/Borland Pascal TPU              *
  519.  
  520.    
  521.    Choosing a Compression Method
  522.    -----------------------------------------------------------------
  523.    When you call CX_COMPRESS, you need to indicate what method of
  524.    compression to use.  This allows you to balance size and speed.
  525.    The following compression methods may be specified:
  526.  
  527.       CX_METHODC  -  fastest compression
  528.       CX_METHODD  -  fastest decompression
  529.       CX_METHOD1  -  general purpose (fastest, but largest)
  530.       CX_METHOD2  -  general purpose (faster, medium size)
  531.       CX_METHOD3  -  general purpose (slowest, smallest)
  532.  
  533.    This is a general guideline only.  You should try different methods
  534.    with your application to determine what works best.
  535.  
  536.  
  537.    What is CX_SLOP?
  538.    ------------------------------------------------------------------
  539.    CX_SLOP is needed for performance reasons.  Cx performs faster when
  540.    it is allowed to slightly overrun buffers that will (or do) contain
  541.    compressed data.  For example:
  542.  
  543.       ibuff = allocate (k) bytes
  544.       obuff = allocate (k+CX_SLOP) bytes   <- a little bigger than k
  545.       CX_COMPRESS(CX_METHOD1, obuff, k, ibuff, k, ...)
  546.  
  547.       ibuff = allocate(k+CX_SLOP) bytes    <- a little bigger than k
  548.       obuff = allocate(k) bytes
  549.       CX_DECOMPRESS(obuff, k, ibuff, k, ...)
  550.  
  551.    Note that CX_SLOP is not included as part of the passed buffer size:
  552.  
  553.       CX_COMPRESS(CX_METHOD1, obuff, k+CX_SLOP, ibuff, k, ...)  <- WRONG!
  554.       CX_DECOMPRESS(obuff, k, ibuff, k+CX_SLOP, ...)            <- WRONG!
  555.  
  556.    In these examples, CX_COMPRESS may write up to CX_SLOP bytes past
  557.    the end of obuff (obuff[k] to obuff[k+CX_SLOP-1]), and CX_DECOMPRESS
  558.    may read up to CX_SLOP bytes past the end of ibuff (ibuff[k] to
  559.    ibuff[k+CX_SLOP-1]).
  560.  
  561.    CX_DECOMPRESS will NOT modify the contents of the slop area in any way,
  562.    and this area does not need to be initialized in any way.  CX_DECOMPRESS
  563.    may simply read this area of memory.  When using Cx with an operating
  564.    system that does not provide memory protection (like MS-DOS), it is not
  565.    necessary to explicitly make room for the slop area when calling
  566.    CX_DECOMPRESS.  Explicitly defining a slop area, however, will make your
  567.    code portable to environments that have memory protection.
  568.    
  569.  
  570.    Memory Considerations / Low Memory Situations
  571.    -----------------------------------------------------------------
  572.    It is best to present large buffers to CX_COMPRESS for maximum
  573.    compression.  At most, this could amount to three 64k buffers
  574.    (approximate), or 192k.  If this is not acceptable, the input
  575.    and output buffers can be made smaller, and/or the temporary
  576.    storage size reduced.  As an extreme example, 8k buffers could
  577.    be used for input and output with temporary storage of 18k
  578.    (CX_C_MINTEMP), for a total of 34k.  The only way to find an
  579.    acceptable solution is to experiment with buffer sizes.  It may also
  580.    be helpful to pass an output buffer smaller than the input buffer
  581.    when compressing if you are sure of a particular level of compression.
  582.    If, for example, you know that compression is always going to be
  583.    about 50%, obuff can be less than the size of ibuff when compressing. 
  584.  
  585.    When decompressing, there are not many alternatives because
  586.    decompression is based on the original buffer sizes.  Note, however,
  587.    the temporary storage required when decompressing is less (7k).
  588.  
  589.    You may be able to reduce memory requirements by choosing a smaller
  590.    version of the object code.  
  591.  
  592.  
  593.    Re-entrancy
  594.    ------------------------------------------------------------------
  595.    All Cx functions are re-entrant.  The Cx functions do not require
  596.    any special programming considerations when used in multi-tasking
  597.    or multi-threaded environments.
  598.  
  599.  
  600.    Handling Uncompressable Data
  601.    ------------------------------------------------------------------
  602.    The included source code demonstrates a good way to handle
  603.    uncompressable data.  Unless you can completely guarantee that your
  604.    application will not encounter uncompressable data, it is a good
  605.    idea to plan for it.  The example programs handle uncompressable
  606.    data as follows:
  607.  
  608.       Stored with each compressed (or uncompressable) buffer are 2
  609.       16 bit integers.  The first integer indicates the size of the
  610.       original buffer and the second integer indicates the size of
  611.       the stored buffer.  If these two integers are identical, the
  612.       application determines that the stored buffer is not compressed.
  613.  
  614.  
  615.    Detecting Errors / Using a CRC
  616.    ------------------------------------------------------------------
  617.    It is not always possible to detect invalid compressed data when
  618.    running CX_DECOMPRESS.  Invalid compressed data meaning data which
  619.    is not the exact output of the compression algorithm.  The main reasons
  620.    you might end up with invalid data are:
  621.  
  622.       Application or System Error                  (bugs, ...)
  623.       Incorrect Application or System Termination  (power failure, ...)
  624.       Undetected Hardware/Storage Failure          (highly unlikely)
  625.  
  626.    Computers are very good at detecting errors in RAM and on disk media.
  627.    It is unlikely that you will have bad RAM or disks, without the
  628.    system informing you.  Many people are very familiar with floppy disk
  629.    failures.  In other words, if you end up with invalid compressed data
  630.    because of a hardware or storage failure, the system will probably
  631.    inform you.
  632.  
  633.    Not being able to detect invalid compressed data is not a weakness in
  634.    CX_DECOMPRESS, but is a consequence of a good compression algorithm.
  635.    A good algorithm will not 'waste' any code space on error conditions.
  636.    In practice, however, most algorithms will be able to detect some
  637.    errors.  When CX_DECOMPRESS detects an error, it will return with the
  638.    value CX_ERR_INVALID.
  639.  
  640.    A good way to detect invalid compressed data is with the use of CRC's.
  641.    A CRC (Cyclical Redundancy Check) basically maps an arbitrarily large
  642.    piece of information into a small integer (typically 16 or 32 bits).
  643.    This mapping is (of course) not reversible (otherwise it would be great
  644.    for data compression!).  There are an infinite number of data buffers
  645.    that have the same CRC.  In practice, however, it is highly unlikely
  646.    that two buffers will have the same CRC (1 in 65535 with a 16 bit
  647.    CRC).  It is even more unlikely for a 'slightly' corrupt buffer to
  648.    have the same CRC as a valid buffer.
  649.  
  650.    To use a CRC to check for invalid data, you store a CRC along with
  651.    the compressed data.  Later, when you want to decompress, you can
  652.    compare the stored CRC with the stored data to ensure the stored
  653.    data is valid.  Typically, a CRC is computed on the original data.
  654.    This provides a lot of confidence that decompressed data is identical to
  655.    the original.  Testing has shown, however, that a CRC computed on the
  656.    compressed data is better able to detect errors.  In addition, this
  657.    has the added advantage of being quicker to compute (as compressed
  658.    buffers will typically be smaller than the original buffer).
  659.  
  660.    The included source code demonstrates how CX_CRC may be used to
  661.    help detect errors.  When an error is detected, however, you do not
  662.    have a lot of options other than informing the operator (as with a
  663.    floppy disk failure).
  664.  
  665.  
  666.    Interfacing to 80x86 Object Code
  667.    --------------------------------------------------------------------
  668.    This section will be of interest primarily to assembly language
  669.    programmers, and users of 80x86 compilers that have not yet been
  670.    tested.  The following notes apply to all 80x86 object code, but
  671.    are of particular use when interfacing to CX.OBJ and CX.LIB.
  672.  
  673.       *  Depending upon the object code used (see section Object Code
  674.          Manager), the following segment will be used:
  675.  
  676.            CODE      SEGMENT 'CODE'    <- 'Normal' segment definition
  677.            CODE      SEGMENT           <- 'Simplified' segment definition
  678.  
  679.          This is the ONLY segment definition used in Cx 80x86 object code.
  680.          The environment used must allow read as well as execute privilege
  681.          to this segment.
  682.  
  683.       *  All buffers passed must be 32 bit pointers using the 80x86
  684.          segmented memory mechanism.  These are typically called 'far'
  685.          pointers.  When interfacing Cx with a 32 bit application, a
  686.          translation typically needs to be made on the pointers being passed.
  687.  
  688.       *  A far call should be placed to all Cx routines.  
  689.  
  690.       *  The pascal calling convention is used.  This convention is common
  691.          for inter-language programming.
  692.  
  693.          As an example, CX_CRC looks like:
  694.  
  695.             CX_CRC(buff, bytes)
  696.                push  bp       
  697.                mov   bp,sp    
  698.  
  699.                ...
  700.                here bp[8..11] contains the 32 bit (far) pointer to buff
  701.                here bp[6..7]  contains the number of bytes
  702.                ...
  703.  
  704.                mov   sp,bp
  705.                pop   bp
  706.                retf  6     <- Far return, 4 bytes for buff, 2 for bytes
  707.             }
  708.  
  709.       *  All 'normal' flags and the following registers may be
  710.          modified by the Cx routines:
  711.  
  712.             AX, BX, CX, DX, ES
  713.    
  714.       *  The AX register contains the return value for all Cx routines.
  715.  
  716.       *  All Cx routines are re-entrant.
  717.  
  718.       *  All Cx routines use less than 256 bytes of stack space.
  719.  
  720.  
  721.    Using Unsigned Integers
  722.    --------------------------------------------------------------------
  723.    The Cx routines accept as parameters, and return, 16 bit unsigned
  724.    integers.  A 16 bit unsigned integer can hold any value between
  725.    (and including) 0 and 65535.
  726.  
  727.    Many languages have direct support for unsigned integers, and need
  728.    no special attention, but others, like BASIC, do not.  For these
  729.    languages, it is suggested that you use long (32 bit) integers
  730.    in your application, and convert to and from 16 bit signed integers
  731.    immediately before and after they are needed.
  732.  
  733.    For example:
  734.  
  735.       k = CX_COMPRESS(..., ltoi(osize), ...
  736.       lk = itol(k)
  737.  
  738.    Where the conversion routines are:
  739.  
  740.       itol(i)  -  if i < 0 then itol = 65536+i else itol = i
  741.       ltoi(l)  -  if l > 32767 then ltoi = l-65536 else ltoi = l
  742.  
  743.  
  744.    Building a Turbo/Borland Pascal TPU
  745.    --------------------------------------------------------------------
  746.    To build CX.TPU, you must compile CX.PAS (tpc cx).  CX.PAS uses
  747.    CX.OBJ.  Use the Object Code Manager to extract the version of
  748.    CX.OBJ you need.  Some versions of Turbo/Borland Pascal require a
  749.    simplified code segment, and others do not.  The Object Code Manager
  750.    will ask you if you want a simplified code segment.  If you are in
  751.    doubt, try it both ways.  You will get a compilation error if you
  752.    are using the wrong version of CX.OBJ.
  753.  
  754.  
  755. Where is the Object Code? / The Object Code Manager
  756. --------------------------------------------------------------------------
  757. There are many different 'builds' of object code that are included with
  758. Cx 2.01.  The reasons for this are listed below:
  759.  
  760.    *  Compilers interface to slightly different types of .OBJ and .LIB
  761.       files.
  762.  
  763.    *  Some applications will need all of the Cx routines, while others will
  764.       only need some.
  765.  
  766.    *  Some applications need the ability to decompress Cx 1.* data, while
  767.       others do not.
  768.  
  769. All of the Cx 2.01 object code is stored in the file OCM.DAT.  Object code
  770. may be extracted from OCM.DAT using the included MS-DOS program OCM.EXE.
  771.  
  772. Simply run OCM.EXE from a directory containing OCM.DAT.
  773.  
  774. When you run OCM, you will be prompted with a series of questions about
  775. the type of object code you want extracted.  The names and types of
  776. object code that may be extracted when running OCM.EXE are listed below:
  777.  
  778.    CX.OBJ      -  linkable in MS-DOS, Windows and OS/2
  779.    CX.LIB      -  linkable in MS-DOS, Windows and OS/2
  780.    CXWIN.DLL   -  Windows 3.*+ DLL
  781.    CXWIN.LIB   -  Windows 3.*+ import library
  782.    CXOS2.DLL   -  OS/2 1.*+ DLL
  783.    CXOS2.LIB   -  OS/2 1.*+ import library
  784.  
  785. It is important to remember that any DLL's you distribute may conflict
  786. with other previously installed Cx DLL's.  For this reason, you should
  787. ensure that you access the DLL's you distribute (i.e. keep them in your
  788. applications directory).
  789.  
  790.  
  791. The CXF Source Code
  792. -------------------------------------------------------------------------
  793. The CXF source code may be used to create an example program which uses
  794. the included object code.  The CXF source code relies heavily on the
  795. CXSUB family of functions.  Source code for these functions is provided
  796. here (see CXSUB.DOC).
  797.  
  798. To compile CXF for many compilers, run:
  799.  
  800.    MCXF.BAT    -  MS-DOS
  801.    MCXF.CMD    -  OS/2
  802.  
  803. To compile CXF for Visual Basic, use the project:
  804.  
  805.    VBCXF.MAK
  806.  
  807. Visual Basic users will also want to examine BINIO.DOC.
  808.  
  809.  
  810.  
  811. Cx 2.01 Ordering Information
  812. -------------------------------------------------------------------------
  813. To purchase Cx 2.01, fill out this ordering form.  You will receive:
  814.  
  815.    *  All Cx 2.01 commercial object code.
  816.    *  The right to distribute Cx 2.01 object code (refer to LICENSE.DOC
  817.       for specific rights) royalty free.
  818.    *  ANSI C and 80x86 assembly language source for Cx 2.01 (if purchased).
  819.    *  Printed documentation and technical support from the author of Cx.
  820.  
  821.    Prices:           $145 USD Cx 2.01
  822.                      $295 USD Cx 2.01 + source
  823.  
  824.                       $45 USD Cx 1.* upgrade to Cx 2.01
  825.                      $195 USD Cx 1.* upgrade to Cx 2.01 + source
  826.                       $45 USD Cx 1.* + source upgrade to Cx 2.01
  827.                       $95 USD Cx 1.* + source upgrade to Cx 2.01 + source
  828.                           Wisconsin residents add 5% sales tax
  829.  
  830.                        $5 USD for non-USA shipping
  831.                       $10 USD for next day delivery (USA only)
  832.                        $3 USD for second day delivery (USA only)
  833.  
  834.    Make Payment To:  Four Lakes Computing
  835.  
  836.    Payment Methods:  US Check, US Money Order, US Dollars,
  837.                      American Express International Money Order.
  838.  
  839.    Send Payment To:  Four Lakes Computing
  840.                      1135 Williamson #4
  841.                      Madison, WI 53703 USA
  842.  
  843.    Address:  __________________________________________________
  844.  
  845.              __________________________________________________
  846.  
  847.              __________________________________________________
  848.  
  849.              __________________________________________________
  850.  
  851.    Other contacts (phone, Compuserve, Internet, ... )
  852.  
  853.              __________________________________________________
  854.  
  855.              __________________________________________________
  856.  
  857.              __________________________________________________
  858.  
  859.              __________________________________________________
  860.  
  861.    PO Number: ________________________ Disk:  ___ 5 1/4  ___ 3 1/2
  862.  
  863.  
  864. If you have any questions, contact the address above or:
  865.  
  866.    US Phone:  608-256-3382         Compuserve ID:  70662,2501
  867.  
  868.